home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 2010 April / PCWorld0410.iso / hity wydania / Ubuntu 9.10 PL / karmelkowy-koliberek-desktop-9.10-i386-PL.iso / casper / filesystem.squashfs / usr / include / mtd / ubi-user.h < prev   
C/C++ Source or Header  |  2009-10-16  |  15KB  |  413 lines
  1. /*
  2.  * Copyright (c) International Business Machines Corp., 2006
  3.  *
  4.  * This program is free software; you can redistribute it and/or modify
  5.  * it under the terms of the GNU General Public License as published by
  6.  * the Free Software Foundation; either version 2 of the License, or
  7.  * (at your option) any later version.
  8.  *
  9.  * This program is distributed in the hope that it will be useful,
  10.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
  12.  * the GNU General Public License for more details.
  13.  *
  14.  * You should have received a copy of the GNU General Public License
  15.  * along with this program; if not, write to the Free Software
  16.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  17.  *
  18.  * Author: Artem Bityutskiy (╨æ╨╕╤é╤Ä╤å╨║╨╕╨╣ ╨É╤Ç╤é╤æ╨╝)
  19.  */
  20.  
  21. #ifndef __UBI_USER_H__
  22. #define __UBI_USER_H__
  23.  
  24. #include <linux/types.h>
  25.  
  26. /*
  27.  * UBI device creation (the same as MTD device attachment)
  28.  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  29.  *
  30.  * MTD devices may be attached using %UBI_IOCATT ioctl command of the UBI
  31.  * control device. The caller has to properly fill and pass
  32.  * &struct ubi_attach_req object - UBI will attach the MTD device specified in
  33.  * the request and return the newly created UBI device number as the ioctl
  34.  * return value.
  35.  *
  36.  * UBI device deletion (the same as MTD device detachment)
  37.  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  38.  *
  39.  * An UBI device maybe deleted with %UBI_IOCDET ioctl command of the UBI
  40.  * control device.
  41.  *
  42.  * UBI volume creation
  43.  * ~~~~~~~~~~~~~~~~~~~
  44.  *
  45.  * UBI volumes are created via the %UBI_IOCMKVOL ioctl command of UBI character
  46.  * device. A &struct ubi_mkvol_req object has to be properly filled and a
  47.  * pointer to it has to be passed to the ioctl.
  48.  *
  49.  * UBI volume deletion
  50.  * ~~~~~~~~~~~~~~~~~~~
  51.  *
  52.  * To delete a volume, the %UBI_IOCRMVOL ioctl command of the UBI character
  53.  * device should be used. A pointer to the 32-bit volume ID hast to be passed
  54.  * to the ioctl.
  55.  *
  56.  * UBI volume re-size
  57.  * ~~~~~~~~~~~~~~~~~~
  58.  *
  59.  * To re-size a volume, the %UBI_IOCRSVOL ioctl command of the UBI character
  60.  * device should be used. A &struct ubi_rsvol_req object has to be properly
  61.  * filled and a pointer to it has to be passed to the ioctl.
  62.  *
  63.  * UBI volumes re-name
  64.  * ~~~~~~~~~~~~~~~~~~~
  65.  *
  66.  * To re-name several volumes atomically at one go, the %UBI_IOCRNVOL command
  67.  * of the UBI character device should be used. A &struct ubi_rnvol_req object
  68.  * has to be properly filled and a pointer to it has to be passed to the ioctl.
  69.  *
  70.  * UBI volume update
  71.  * ~~~~~~~~~~~~~~~~~
  72.  *
  73.  * Volume update should be done via the %UBI_IOCVOLUP ioctl command of the
  74.  * corresponding UBI volume character device. A pointer to a 64-bit update
  75.  * size should be passed to the ioctl. After this, UBI expects user to write
  76.  * this number of bytes to the volume character device. The update is finished
  77.  * when the claimed number of bytes is passed. So, the volume update sequence
  78.  * is something like:
  79.  *
  80.  * fd = open("/dev/my_volume");
  81.  * ioctl(fd, UBI_IOCVOLUP, &image_size);
  82.  * write(fd, buf, image_size);
  83.  * close(fd);
  84.  *
  85.  * Logical eraseblock erase
  86.  * ~~~~~~~~~~~~~~~~~~~~~~~~
  87.  *
  88.  * To erase a logical eraseblock, the %UBI_IOCEBER ioctl command of the
  89.  * corresponding UBI volume character device should be used. This command
  90.  * unmaps the requested logical eraseblock, makes sure the corresponding
  91.  * physical eraseblock is successfully erased, and returns.
  92.  *
  93.  * Atomic logical eraseblock change
  94.  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  95.  *
  96.  * Atomic logical eraseblock change operation is called using the %UBI_IOCEBCH
  97.  * ioctl command of the corresponding UBI volume character device. A pointer to
  98.  * a &struct ubi_leb_change_req object has to be passed to the ioctl. Then the
  99.  * user is expected to write the requested amount of bytes (similarly to what
  100.  * should be done in case of the "volume update" ioctl).
  101.  *
  102.  * Logical eraseblock map
  103.  * ~~~~~~~~~~~~~~~~~~~~~
  104.  *
  105.  * To map a logical eraseblock to a physical eraseblock, the %UBI_IOCEBMAP
  106.  * ioctl command should be used. A pointer to a &struct ubi_map_req object is
  107.  * expected to be passed. The ioctl maps the requested logical eraseblock to
  108.  * a physical eraseblock and returns.  Only non-mapped logical eraseblocks can
  109.  * be mapped. If the logical eraseblock specified in the request is already
  110.  * mapped to a physical eraseblock, the ioctl fails and returns error.
  111.  *
  112.  * Logical eraseblock unmap
  113.  * ~~~~~~~~~~~~~~~~~~~~~~~~
  114.  *
  115.  * To unmap a logical eraseblock to a physical eraseblock, the %UBI_IOCEBUNMAP
  116.  * ioctl command should be used. The ioctl unmaps the logical eraseblocks,
  117.  * schedules corresponding physical eraseblock for erasure, and returns. Unlike
  118.  * the "LEB erase" command, it does not wait for the physical eraseblock being
  119.  * erased. Note, the side effect of this is that if an unclean reboot happens
  120.  * after the unmap ioctl returns, you may find the LEB mapped again to the same
  121.  * physical eraseblock after the UBI is run again.
  122.  *
  123.  * Check if logical eraseblock is mapped
  124.  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  125.  *
  126.  * To check if a logical eraseblock is mapped to a physical eraseblock, the
  127.  * %UBI_IOCEBISMAP ioctl command should be used. It returns %0 if the LEB is
  128.  * not mapped, and %1 if it is mapped.
  129.  *
  130.  * Set an UBI volume property
  131.  * ~~~~~~~~~~~~~~~~~~~~~~~~~
  132.  *
  133.  * To set an UBI volume property the %UBI_IOCSETPROP ioctl command should be
  134.  * used. A pointer to a &struct ubi_set_prop_req object is expected to be
  135.  * passed. The object describes which property should be set, and to which value
  136.  * it should be set.
  137.  */
  138.  
  139. /*
  140.  * When a new UBI volume or UBI device is created, users may either specify the
  141.  * volume/device number they want to create or to let UBI automatically assign
  142.  * the number using these constants.
  143.  */
  144. #define UBI_VOL_NUM_AUTO (-1)
  145. #define UBI_DEV_NUM_AUTO (-1)
  146.  
  147. /* Maximum volume name length */
  148. #define UBI_MAX_VOLUME_NAME 127
  149.  
  150. /* ioctl commands of UBI character devices */
  151.  
  152. #define UBI_IOC_MAGIC 'o'
  153.  
  154. /* Create an UBI volume */
  155. #define UBI_IOCMKVOL _IOW(UBI_IOC_MAGIC, 0, struct ubi_mkvol_req)
  156. /* Remove an UBI volume */
  157. #define UBI_IOCRMVOL _IOW(UBI_IOC_MAGIC, 1, __s32)
  158. /* Re-size an UBI volume */
  159. #define UBI_IOCRSVOL _IOW(UBI_IOC_MAGIC, 2, struct ubi_rsvol_req)
  160. /* Re-name volumes */
  161. #define UBI_IOCRNVOL _IOW(UBI_IOC_MAGIC, 3, struct ubi_rnvol_req)
  162.  
  163. /* ioctl commands of the UBI control character device */
  164.  
  165. #define UBI_CTRL_IOC_MAGIC 'o'
  166.  
  167. /* Attach an MTD device */
  168. #define UBI_IOCATT _IOW(UBI_CTRL_IOC_MAGIC, 64, struct ubi_attach_req)
  169. /* Detach an MTD device */
  170. #define UBI_IOCDET _IOW(UBI_CTRL_IOC_MAGIC, 65, __s32)
  171.  
  172. /* ioctl commands of UBI volume character devices */
  173.  
  174. #define UBI_VOL_IOC_MAGIC 'O'
  175.  
  176. /* Start UBI volume update */
  177. #define UBI_IOCVOLUP _IOW(UBI_VOL_IOC_MAGIC, 0, __s64)
  178. /* LEB erasure command, used for debugging, disabled by default */
  179. #define UBI_IOCEBER _IOW(UBI_VOL_IOC_MAGIC, 1, __s32)
  180. /* Atomic LEB change command */
  181. #define UBI_IOCEBCH _IOW(UBI_VOL_IOC_MAGIC, 2, __s32)
  182. /* Map LEB command */
  183. #define UBI_IOCEBMAP _IOW(UBI_VOL_IOC_MAGIC, 3, struct ubi_map_req)
  184. /* Unmap LEB command */
  185. #define UBI_IOCEBUNMAP _IOW(UBI_VOL_IOC_MAGIC, 4, __s32)
  186. /* Check if LEB is mapped command */
  187. #define UBI_IOCEBISMAP _IOR(UBI_VOL_IOC_MAGIC, 5, __s32)
  188. /* Set an UBI volume property */
  189. #define UBI_IOCSETPROP _IOW(UBI_VOL_IOC_MAGIC, 6, struct ubi_set_prop_req)
  190.  
  191. /* Maximum MTD device name length supported by UBI */
  192. #define MAX_UBI_MTD_NAME_LEN 127
  193.  
  194. /* Maximum amount of UBI volumes that can be re-named at one go */
  195. #define UBI_MAX_RNVOL 32
  196.  
  197. /*
  198.  * UBI data type hint constants.
  199.  *
  200.  * UBI_LONGTERM: long-term data
  201.  * UBI_SHORTTERM: short-term data
  202.  * UBI_UNKNOWN: data persistence is unknown
  203.  *
  204.  * These constants are used when data is written to UBI volumes in order to
  205.  * help the UBI wear-leveling unit to find more appropriate physical
  206.  * eraseblocks.
  207.  */
  208. enum {
  209.     UBI_LONGTERM  = 1,
  210.     UBI_SHORTTERM = 2,
  211.     UBI_UNKNOWN   = 3,
  212. };
  213.  
  214. /*
  215.  * UBI volume type constants.
  216.  *
  217.  * @UBI_DYNAMIC_VOLUME: dynamic volume
  218.  * @UBI_STATIC_VOLUME:  static volume
  219.  */
  220. enum {
  221.     UBI_DYNAMIC_VOLUME = 3,
  222.     UBI_STATIC_VOLUME  = 4,
  223. };
  224.  
  225. /*
  226.  * UBI set property ioctl constants
  227.  *
  228.  * @UBI_PROP_DIRECT_WRITE: allow / disallow user to directly write and
  229.  *                         erase individual eraseblocks on dynamic volumes
  230.  */
  231. enum {
  232.        UBI_PROP_DIRECT_WRITE = 1,
  233. };
  234.  
  235. /**
  236.  * struct ubi_attach_req - attach MTD device request.
  237.  * @ubi_num: UBI device number to create
  238.  * @mtd_num: MTD device number to attach
  239.  * @vid_hdr_offset: VID header offset (use defaults if %0)
  240.  * @padding: reserved for future, not used, has to be zeroed
  241.  *
  242.  * This data structure is used to specify MTD device UBI has to attach and the
  243.  * parameters it has to use. The number which should be assigned to the new UBI
  244.  * device is passed in @ubi_num. UBI may automatically assign the number if
  245.  * @UBI_DEV_NUM_AUTO is passed. In this case, the device number is returned in
  246.  * @ubi_num.
  247.  *
  248.  * Most applications should pass %0 in @vid_hdr_offset to make UBI use default
  249.  * offset of the VID header within physical eraseblocks. The default offset is
  250.  * the next min. I/O unit after the EC header. For example, it will be offset
  251.  * 512 in case of a 512 bytes page NAND flash with no sub-page support. Or
  252.  * it will be 512 in case of a 2KiB page NAND flash with 4 512-byte sub-pages.
  253.  *
  254.  * But in rare cases, if this optimizes things, the VID header may be placed to
  255.  * a different offset. For example, the boot-loader might do things faster if
  256.  * the VID header sits at the end of the first 2KiB NAND page with 4 sub-pages.
  257.  * As the boot-loader would not normally need to read EC headers (unless it
  258.  * needs UBI in RW mode), it might be faster to calculate ECC. This is weird
  259.  * example, but it real-life example. So, in this example, @vid_hdr_offer would
  260.  * be 2KiB-64 bytes = 1984. Note, that this position is not even 512-bytes
  261.  * aligned, which is OK, as UBI is clever enough to realize this is 4th
  262.  * sub-page of the first page and add needed padding.
  263.  */
  264. struct ubi_attach_req {
  265.     __s32 ubi_num;
  266.     __s32 mtd_num;
  267.     __s32 vid_hdr_offset;
  268.     __s8 padding[12];
  269. };
  270.  
  271. /**
  272.  * struct ubi_mkvol_req - volume description data structure used in
  273.  *                        volume creation requests.
  274.  * @vol_id: volume number
  275.  * @alignment: volume alignment
  276.  * @bytes: volume size in bytes
  277.  * @vol_type: volume type (%UBI_DYNAMIC_VOLUME or %UBI_STATIC_VOLUME)
  278.  * @padding1: reserved for future, not used, has to be zeroed
  279.  * @name_len: volume name length
  280.  * @padding2: reserved for future, not used, has to be zeroed
  281.  * @name: volume name
  282.  *
  283.  * This structure is used by user-space programs when creating new volumes. The
  284.  * @used_bytes field is only necessary when creating static volumes.
  285.  *
  286.  * The @alignment field specifies the required alignment of the volume logical
  287.  * eraseblock. This means, that the size of logical eraseblocks will be aligned
  288.  * to this number, i.e.,
  289.  *    (UBI device logical eraseblock size) mod (@alignment) = 0.
  290.  *
  291.  * To put it differently, the logical eraseblock of this volume may be slightly
  292.  * shortened in order to make it properly aligned. The alignment has to be
  293.  * multiple of the flash minimal input/output unit, or %1 to utilize the entire
  294.  * available space of logical eraseblocks.
  295.  *
  296.  * The @alignment field may be useful, for example, when one wants to maintain
  297.  * a block device on top of an UBI volume. In this case, it is desirable to fit
  298.  * an integer number of blocks in logical eraseblocks of this UBI volume. With
  299.  * alignment it is possible to update this volume using plane UBI volume image
  300.  * BLOBs, without caring about how to properly align them.
  301.  */
  302. struct ubi_mkvol_req {
  303.     __s32 vol_id;
  304.     __s32 alignment;
  305.     __s64 bytes;
  306.     __s8 vol_type;
  307.     __s8 padding1;
  308.     __s16 name_len;
  309.     __s8 padding2[4];
  310.     char name[UBI_MAX_VOLUME_NAME + 1];
  311. } __attribute__ ((packed));
  312.  
  313. /**
  314.  * struct ubi_rsvol_req - a data structure used in volume re-size requests.
  315.  * @vol_id: ID of the volume to re-size
  316.  * @bytes: new size of the volume in bytes
  317.  *
  318.  * Re-sizing is possible for both dynamic and static volumes. But while dynamic
  319.  * volumes may be re-sized arbitrarily, static volumes cannot be made to be
  320.  * smaller than the number of bytes they bear. To arbitrarily shrink a static
  321.  * volume, it must be wiped out first (by means of volume update operation with
  322.  * zero number of bytes).
  323.  */
  324. struct ubi_rsvol_req {
  325.     __s64 bytes;
  326.     __s32 vol_id;
  327. } __attribute__ ((packed));
  328.  
  329. /**
  330.  * struct ubi_rnvol_req - volumes re-name request.
  331.  * @count: count of volumes to re-name
  332.  * @padding1:  reserved for future, not used, has to be zeroed
  333.  * @vol_id: ID of the volume to re-name
  334.  * @name_len: name length
  335.  * @padding2:  reserved for future, not used, has to be zeroed
  336.  * @name: new volume name
  337.  *
  338.  * UBI allows to re-name up to %32 volumes at one go. The count of volumes to
  339.  * re-name is specified in the @count field. The ID of the volumes to re-name
  340.  * and the new names are specified in the @vol_id and @name fields.
  341.  *
  342.  * The UBI volume re-name operation is atomic, which means that should power cut
  343.  * happen, the volumes will have either old name or new name. So the possible
  344.  * use-cases of this command is atomic upgrade. Indeed, to upgrade, say, volumes
  345.  * A and B one may create temporary volumes %A1 and %B1 with the new contents,
  346.  * then atomically re-name A1->A and B1->B, in which case old %A and %B will
  347.  * be removed.
  348.  *
  349.  * If it is not desirable to remove old A and B, the re-name request has to
  350.  * contain 4 entries: A1->A, A->A1, B1->B, B->B1, in which case old A1 and B1
  351.  * become A and B, and old A and B will become A1 and B1.
  352.  *
  353.  * It is also OK to request: A1->A, A1->X, B1->B, B->Y, in which case old A1
  354.  * and B1 become A and B, and old A and B become X and Y.
  355.  *
  356.  * In other words, in case of re-naming into an existing volume name, the
  357.  * existing volume is removed, unless it is re-named as well at the same
  358.  * re-name request.
  359.  */
  360. struct ubi_rnvol_req {
  361.     __s32 count;
  362.     __s8 padding1[12];
  363.     struct {
  364.         __s32 vol_id;
  365.         __s16 name_len;
  366.         __s8  padding2[2];
  367.         char    name[UBI_MAX_VOLUME_NAME + 1];
  368.     } ents[UBI_MAX_RNVOL];
  369. } __attribute__ ((packed));
  370.  
  371. /**
  372.  * struct ubi_leb_change_req - a data structure used in atomic LEB change
  373.  *                             requests.
  374.  * @lnum: logical eraseblock number to change
  375.  * @bytes: how many bytes will be written to the logical eraseblock
  376.  * @dtype: data type (%UBI_LONGTERM, %UBI_SHORTTERM, %UBI_UNKNOWN)
  377.  * @padding: reserved for future, not used, has to be zeroed
  378.  */
  379. struct ubi_leb_change_req {
  380.     __s32 lnum;
  381.     __s32 bytes;
  382.     __s8  dtype;
  383.     __s8  padding[7];
  384. } __attribute__ ((packed));
  385.  
  386. /**
  387.  * struct ubi_map_req - a data structure used in map LEB requests.
  388.  * @lnum: logical eraseblock number to unmap
  389.  * @dtype: data type (%UBI_LONGTERM, %UBI_SHORTTERM, %UBI_UNKNOWN)
  390.  * @padding: reserved for future, not used, has to be zeroed
  391.  */
  392. struct ubi_map_req {
  393.     __s32 lnum;
  394.     __s8  dtype;
  395.     __s8  padding[3];
  396. } __attribute__ ((packed));
  397.  
  398.  
  399. /**
  400.  * struct ubi_set_prop_req - a data structure used to set an ubi volume
  401.  *                           property.
  402.  * @property: property to set (%UBI_PROP_DIRECT_WRITE)
  403.  * @padding: reserved for future, not used, has to be zeroed
  404.  * @value: value to set
  405.  */
  406. struct ubi_set_prop_req {
  407.        __u8  property;
  408.        __u8  padding[7];
  409.        __u64 value;
  410. }  __attribute__ ((packed));
  411.  
  412. #endif /* __UBI_USER_H__ */
  413.